Note As part of our ongoing commitment to best security practices, we have rotated the signing keys used to sign previous releases of this SDK. As a result, new patch builds have been released using the new signing key. Please upgrade at your earliest convenience.
While this change won't affect most developers, if you have implemented a dependency signature validation step in your build process, you may notice a warning that past releases can't be verified. This is expected, and a result of the key rotation process. Updating to the latest version will resolve this for you.
📚 Documentation - 🚀 Getting Started - 💻 API Reference 💬 Feedback
- Examples - code samples for common java-jwt scenarios.
- Docs site - explore our docs site and learn more about Auth0.
This library is supported for Java LTS versions 8, 11, and 17. For issues on non-LTS versions above 8, consideration will be given on a case-by-case basis.
java-jwt
is intended for server-side JVM applications. Android applications should use JWTDecode.Android.
java-jwt
supports the following algorithms for both signing and verification:
JWS | Algorithm | Description |
---|---|---|
HS256 | HMAC256 | HMAC with SHA-256 |
HS384 | HMAC384 | HMAC with SHA-384 |
HS512 | HMAC512 | HMAC with SHA-512 |
RS256 | RSA256 | RSASSA-PKCS1-v1_5 with SHA-256 |
RS384 | RSA384 | RSASSA-PKCS1-v1_5 with SHA-384 |
RS512 | RSA512 | RSASSA-PKCS1-v1_5 with SHA-512 |
ES256 | ECDSA256 | ECDSA with curve P-256 and SHA-256 |
ES384 | ECDSA384 | ECDSA with curve P-384 and SHA-384 |
ES512 | ECDSA512 | ECDSA with curve P-521 and SHA-512 |
Note - Support for ECDSA with curve secp256k1 and SHA-256 (ES256K) has been dropped since it has been disabled in Java 15
⚠️ Important security note: JVM has a critical vulnerability for ECDSA Algorithms - CVE-2022-21449. Please review the details of the vulnerability and update your environment.
Add the dependency via Maven:
<dependency>
<groupId>com.auth0</groupId>
<artifactId>java-jwt</artifactId>
<version>4.4.0</version>
</dependency>
or Gradle:
implementation 'com.auth0:java-jwt:4.4.0'
Use JWT.create()
, configure the claims, and then call sign(algorithm)
to sign the JWT.
The example below demonstrates this using the RS256
signing algorithm:
try {
Algorithm algorithm = Algorithm.RSA256(rsaPublicKey, rsaPrivateKey);
String token = JWT.create()
.withIssuer("auth0")
.sign(algorithm);
} catch (JWTCreationException exception){
// Invalid Signing configuration / Couldn't convert Claims.
}
Create a JWTVerifier
passing the Algorithm
, and specify any required claim values.
The following example uses RS256
to verify the JWT.
String token = "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXUyJ9.eyJpc3MiOiJhdXRoMCJ9.AbIJTDMFc7yUa5MhvcP03nJPyCPzZtQcGEp-zWfOkEE";
DecodedJWT decodedJWT;
try {
Algorithm algorithm = Algorithm.RSA256(rsaPublicKey, rsaPrivateKey);
JWTVerifier verifier = JWT.require(algorithm)
// specify an specific claim validations
.withIssuer("auth0")
// reusable verifier instance
.build();
decodedJWT = verifier.verify(token);
} catch (JWTVerificationException exception){
// Invalid signature/claims
}
If the token has an invalid signature or the Claim requirement is not met, a JWTVerificationException
will be thrown.